Rapha Markdown Styleguide
Overview
This document serves as the complete definition of Rapha’s coding standards for source code in the Markdown markup language. A Markdown file is described as being in Rapha Style if and only if it adheres to the rules herein.
Guide
Document Layout
In general, most documents benefit from some variation of the following layout:
---
id: document-id
title: Document Title
description: Document Description
keywords: [keyword]
author: [someone]
---
# Document Title
[TOC]
## Overview
Short introduction.
## Topic(s)
Content.
...
## Resources
- [Google Markdown Styleguide](https://google.github.io/styleguide/docguide/style.html)
metadata: Metadata in YAML. Usually very useful to set things such as authors and helps with link unfurling.# Document Title: The first heading should be a level one heading, and should ideally be the same or nearly the same as the filename.[TOC]: Adding a table of contents after the document title keeps our documents consistent. This can be omitted if we only have an overview or single topic.## Overview / Short introduction: 1-3 sentences providing a high-level overview of the topic.## Topic: The rest of your headings should start from level 2.## Resources: Put miscellaneous links at the bottom for the user who wants to know more or didn't find what they needed.
Headings
ATX-style headings
## Heading 2
Headings with = or - underlines can be annoying to maintain and don’t fit with the rest of the heading syntax. The user has to ask: Does --- mean H1 or H2?
Heading - do you remember what level? DO NOT DO THIS.
---------
Add spacing to headings
Prefer spacing after # and newlines before and after:
...text before.
# Heading 1
Text after...
Lack of spacing makes it a little harder to read in source:
...text before.
#Heading 1
Text after... DO NOT DO THIS.
Paragraphs, emphasis, wrapping and horizontal lines
Regular paragraphs are obtained by just writing text lines. If you hit enter between two lines, both lines will be joined into a single paragraph, which is called wrapping text. But, if you leave a blank line between them, they will split into two paragraphs.
Emphasis
To display bold or italic text, wrap it in 2 stars (for bold) or underscores (for italic). For both italic and bold, wrap it in 3 stars:
This is **bold** and this is _italic_.
This is **_bold and italic_**.
This is also ***bold and italic***.
This is bold and this is italic.
This is bold and italic.
Markdown doesn't natively support underlined text. However, with Docusaurus we are able to use MDX. This allows us to write JSX within our Markdown files and render react components. If we REALLY want underlined text or extended UI we can do the following:
export const Underline = ({ children, color }) => (
<span
style={{
textDecoration: `underline ${color}`,
}}
>
{children}
</span>
);
<Underline color='#25c2a0'>Hello World</Underline>;
Wrapping Text
Splitting long lines (prefered line length of 100 characters) can make it easier to provide feedback on small chunks of text. Do not leave blank spaces after the last word of the line broken within a paragraph, unless you want it to be intentionally broken with a <br>.
Input
This text is a paragraph.
This won't be another paragraph, it will join the line above it.
This will be another paragraph, as it has a blank line above it.
Output
This text is a paragraph. This won't be another paragraph, it will join the line above it.
This will be another paragraph, as it has a blank line above it.
Horizontal lines
A sequence of three (or more) dashes will produce a horizontal line. Leave blank lines after and before it:
Text
<!-- blank line -->
----
<!-- blank line -->
Text
Links
There are a few different ways to display links with markdown markup. Try not to use meaningless text for links such as "read here" or "this is a link".
Inline Links
We'd rather use inline links, such as [Text to display](link), as they are easier to maintain. To make an inline link open in a new tab, you can add {:target="_blank"} to the end. Ex: [Text to display](link){:target="_blank"}.
Mailto links
If you're adding an email address to a page be sure to format your link with mailto to avoid creating broken links. For example, [example@rapha.cc](mailto:example@rapha.cc)
Identifiers
When there are repeated links across a single page, you can opt for using identifiers.
Place the identifiers at the end of the paragraph (or the section), arranging them in alphabetical order.
[Text to display][identifier] will display a link.
[Another text][another-identifier] will do the same. Hover the mouse over it to see the title.
[This link] will do the same as well. It works as the identifier itself.
[This link][] (same as above), has a second pair of empty brackets to indicate that the following parenthesis does not contain a link.
<https://example.com> works too. Must be used for explicit links.
<!-- Identifiers, in alphabetical order -->
[another-identifier]: https://example.com 'This example has a title'
[identifier]: http://example1.com
[this link]: http://example2.com
Images
Use images sparingly, and prefer simple screenshots. This guide is designed around the idea that plain text gets users down to the business of communication faster with less reader distraction and author procrastination. However, it’s sometimes very helpful to show what you mean.
To insert images to your markdown file, use the markup . As this guide is focussed on markdown that will be used to write our documentation, images should be placed in the static folder. This means that because our baseUrl is baseUrl: '/', the image /static/img/docusaurus.png will be served at /img/docusaurus.png. More information can be found here.
You can also use an identifier, as we do for links:
![Semantic description of image][identifier]
If you want to add a caption to your image, it's easily achieved with:
_My caption_
For clickable images, simply wrap the image markup into a link markup:
[_My caption_][rapha.cc]
Lists
Both ordered and unordered lists are very straightforward to produce. There are a few ways to produce the same results, but let's stick with the following, again, to maintain some standards.
Always use 3 blank spaces to indent a nested list (to create sub items). 3 seems to be the default for VSCode, we can however implement our own markdownlint if we feel 4 is more appropriate.
Use lazy numbering for long lists
Markdown is smart enough to let the resulting HTML render your numbered lists correctly. For longer lists that may change, especially long nested lists, use "lazy" numbering:
1. Foo.
1. Bar.
1. Foofoo.
1. Barbar.
1. Baz.
However, if the list is small and you don't anticipate changing it, prefer fully
numbered lists, because it's nicer to read in source:
```markdown
1. Foo.
2. Bar.
3. Baz.
```
### Nested list spacing
```markdown
1. Item one
1. Sub item one
1. Sub item two
1. Sub item three
1. Item two
```
Even when there's no nesting, using the 4 space indent makes layout consistent
for wrapped text:
```markdown
- Foo,
wrapped.
1. 2 spaces
and 4 space indenting.
2. 2 spaces again.
```
However, when lists are small, not nested, and a single line, one space can
suffice for both kinds of lists:
```markdown
- Foo
- Bar
- Baz.
1. Foo.
2. Bar.
```
## Code
### Inline Code
```markdown
This is an `in-line` code block.
```
### Fenced Code Blocks
It is best practice to explicitly declare the language, so that neither the syntax highlighter nor the next editor must guess.
````markdown
```python
def Foo(self, bar):
self.bar = bar
```
Escape newlines
Because most commandline snippets are intended to be copied and pasted directly into a terminal, it’s best practice to escape any newlines. Use a single backslash at the end of the line:
```shell
bazel run :target -- --flag --foo=longlonglonglonglongvalue \
--bar=anotherlonglonglonglonglonglonglonglonglonglongvalue
```